Summary

Conversation API endpoint was wired through agent_usage with source='api' and userId=keyData.keyId, but:

• agent_usage_source_check only accepts 'studio'|'byoa'
• agent_usage.user_id FK → profiles(id), API key id is not a profile

Both fire on the first DB call. System was never production-deployed (no data to migrate). Fix restructures the model before the route can be safely opened.

Why a separate table, not nullable user_id in agent_usage

Reviewed during this session. The "nullable user_id + COALESCE-UNIQUE" shape was rejected because:

• API key actors differ from user actors (lifecycle, scope, permissions, cap semantics)
• (workspace, user, month, source) UNIQUE doesn't naturally extend with COALESCE — UNIQUE acrobatics for an alien actor
• MCP Cloud keys will need the same key-keyed aggregate; pattern repeats

A dedicated api_message_usage table:

• Preserves DB-enforced FK integrity end-to-end
• Studio chat path untouched → zero regression surface
• Trivially extensible for MCP Cloud later (same shape, different FK target)
• Reporting via UNION/view if cross-actor totals are ever needed

Changes

Migration 006_api_message_usage_and_conversation_actor.sql

1. api_message_usage (workspace, api_key, month) aggregate, RLS for workspace admins, service-role writes only.
2. increment_api_usage_if_allowed RPC — enforces per-key cap AND workspace plan cap in one advisory-locked tx; reports which cap fired via reason discriminator ('ok' | 'key_limit' | 'workspace_limit').
3. increment_api_usage_tokens RPC for post-AI token accounting.
4. conversations.user_id relaxed to nullable; api_key_id uuid FK→conversation_api_keys ON DELETE CASCADE added; CHECK (num_nonnulls(user_id, api_key_id) = 1) enforces exactly one actor.

Provider surface

• incrementAPIUsageIfAllowed / updateAPIUsageTokens RPC wrappers
• createApiConversation — explicit method, not an overload, so call sites state intent
• getConversation filter is now a discriminated union: { userId: string } | { apiKeyId: string }
• getWorkspaceMonthlyAPIUsage repointed to new table (was reading always-empty agent_usage.source='api')

EE wiring

• conversation-api.ts uses the new RPC + helpers; computes both caps via getEffectiveLimit (overage-enabled flows soft-cap correctly); 429 message names the right limit.
• conversation-keys.ts update path now clamps monthly_message_limit to the workspace's current api.messages_per_month cap. Plan downgrades can no longer leave stale-high key limits.

Studio path

• agent_usage schema and RPCs untouched.
• saveChatResult source param narrowed to 'byoa' | 'studio' — 'api' is invalid by construction now and routes through saveApiChatResult.

Out of scope (separate PRs, per agreed roadmap)

• Aborted/failed billing semantics (commit_or_revert)
• History budget refactor / source-aware budget
• Prompt cache + AIProvider system-block array
• Structured tool trace persistence (messages.content_blocks)
• listConversations/deleteConversation for API keys (EE handler doesn't call them)

Test plan

• pnpm typecheck clean
• pnpm lint — 0 errors on changed files (only pre-existing warnings)
• pnpm test:unit — 404 passed (was 403; new saveApiChatResult test added)
• Apply migration to a Supabase test instance; verify the RPC returns { allowed: false, reason: 'key_limit' } and 'workspace_limit' under their respective scenarios
• Manual: create a conversation key, hit /api/conversation/v1/{projectId}/message — must return 200 (or a feature-gate 403), no 500